

<!DOCTYPE html>


<html lang="en" data-content_root="./" >

  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>API Reference &#8212; nvtx</title>
  
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
  </script>
  <!--
    this give us a css class that will be invisible only if js is disabled
  -->
  <noscript>
    <style>
      .pst-js-only { display: none !important; }

    </style>
  </noscript>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="_static/styles/theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />

    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
    <link rel="stylesheet" type="text/css" href="_static/styles/nvidia-sphinx-theme.css?v=df3ac72c" />
  
  <!-- So that users can add custom icons -->
  <script src="_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script>
  <!-- Pre-loaded scripts that we'll load fully later -->
  <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />

    <script src="_static/documentation_options.js?v=29c81e07"></script>
    <script src="_static/doctools.js?v=9bcbadda"></script>
    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script>DOCUMENTATION_OPTIONS.pagename = 'reference';</script>
    <link rel="icon" href="_static/favicon.png"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="prev" title="Automatic function annotation" href="automatic_annotations.html" />

  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
  <meta name="docsearch:version" content="" />


  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

  
  
  <div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
  
  <div id="pst-scroll-pixel-helper"></div>
  
  <button type="button" class="btn rounded-pill" id="pst-back-to-top">
    <i class="fa-solid fa-arrow-up"></i>Back to top</button>

  
  <dialog id="pst-search-dialog">
    
<form class="bd-search d-flex align-items-center"
      action="search.html"
      method="get">
  <i class="fa-solid fa-magnifying-glass"></i>
  <input type="search"
         class="form-control"
         name="q"
         placeholder="Search the docs ..."
         aria-label="Search the docs ..."
         autocomplete="off"
         autocorrect="off"
         autocapitalize="off"
         spellcheck="false"/>
  <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form>
  </dialog>

  <div class="pst-async-banner-revealer d-none">
  <aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>

  
    <header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
  <button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation">
    <span class="fa-solid fa-bars"></span>
  </button>
  
  
  <div class="col-lg-3 navbar-header-items__start">
    
      <div class="navbar-item">

  
    
  

<a class="navbar-brand logo" href="index.html">
  
  
  
  
  
    
    
      
    
    
    <img src="_static/nvidia-logo-horiz-rgb-blk-for-screen.svg" class="logo__image only-light" alt="nvtx - Home"/>
    <img src="_static/nvidia-logo-horiz-rgb-wht-for-screen.svg" class="logo__image only-dark pst-js-only" alt="nvtx - Home"/>
  
  
    <p class="title logo__title">nvtx</p>
  
</a></div>
    
  </div>
  
  <div class="col-lg-9 navbar-header-items">
    
    
    <div class="navbar-header-items__end">
      
        <div class="navbar-item navbar-persistent--container">
          

<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
 <i class="fa-solid fa-magnifying-glass"></i>
 <span class="search-button__default-text">Search</span>
 <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
        </div>
      
      
        <div class="navbar-item">

<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode"  data-bs-placement="bottom" data-bs-toggle="tooltip">
  <i class="theme-switch fa-solid fa-sun                fa-lg" data-mode="light" title="Light"></i>
  <i class="theme-switch fa-solid fa-moon               fa-lg" data-mode="dark"  title="Dark"></i>
  <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"  title="System Settings"></i>
</button></div>
      
    </div>
    
  </div>
  
  
    <div class="navbar-persistent--mobile">

<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
 <i class="fa-solid fa-magnifying-glass"></i>
 <span class="search-button__default-text">Search</span>
 <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
    </div>
  

  
    <button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page">
      <span class="fa-solid fa-outdent"></span>
    </button>
  
</div>

    </header>
  

  <div class="bd-container">
    <div class="bd-container__inner bd-page-width">
      
      
      
      <dialog id="pst-primary-sidebar-modal"></dialog>
      <div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar">
        



  
    
  

<a class="navbar-brand logo" href="index.html">
  
  
  
  
  
    
    
      
    
    
    <img src="_static/nvidia-logo-horiz-rgb-blk-for-screen.svg" class="logo__image only-light" alt="nvtx - Home"/>
    <img src="_static/nvidia-logo-horiz-rgb-wht-for-screen.svg" class="logo__image only-dark pst-js-only" alt="nvtx - Home"/>
  
  
    <p class="title logo__title">nvtx</p>
  
</a>


  
  <div class="sidebar-header-items sidebar-primary__section">
    
    
    
    
      <div class="sidebar-header-items__end">
        
          <div class="navbar-item">

<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode"  data-bs-placement="bottom" data-bs-toggle="tooltip">
  <i class="theme-switch fa-solid fa-sun                fa-lg" data-mode="light" title="Light"></i>
  <i class="theme-switch fa-solid fa-moon               fa-lg" data-mode="dark"  title="Dark"></i>
  <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"  title="System Settings"></i>
</button></div>
        
      </div>
    
  </div>
  
    <div class="sidebar-primary-items__start sidebar-primary__section">
        <div class="sidebar-primary-item">



<nav class="bd-docs-nav bd-links"
     aria-label="Table of Contents">
  <p class="bd-links__title" role="heading" aria-level="1">Table of Contents</p>
  <div class="bd-toc-item navbar-nav"><ul class="nav bd-sidenav">
<li class="toctree-l1 has-children"><a class="reference internal" href="overview.html">Overview</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="annotate.html">Function Decorator and Context Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="annotation_types.html">Annotation Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="annotation_attributes.html">Annotation Attributes</a></li>
<li class="toctree-l2"><a class="reference internal" href="best_practices.html">Best practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="automatic_annotations.html">Automatic function annotation</a></li>
</ul>
</details></li>
</ul>
<ul class="current nav bd-sidenav">
<li class="toctree-l1 current active"><a class="current reference internal" href="#">API Reference</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Project Links</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference external" href="https://github.com/NVIDIA/NVTX/">GitHub</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pypi.org/project/nvtx/">PyPI</a></li>
<li class="toctree-l1"><a class="reference external" href="https://nvidia.github.io/NVTX/doxygen/">C Docs</a></li>
<li class="toctree-l1"><a class="reference external" href="https://nvidia.github.io/NVTX/doxygen-cpp/">C++ Docs</a></li>
</ul>
</div>
</nav></div>
    </div>
  
  
  <div class="sidebar-primary-items__end sidebar-primary__section">
  </div>



      </div>
      
      <main id="main-content" class="bd-main" role="main">
        
        
          <div class="bd-content">
            <div class="bd-article-container">
              
              <div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
  
    <div class="header-article-items__start">
      
        <div class="header-article-item">

<nav aria-label="Breadcrumb" class="d-print-none">
  <ul class="bd-breadcrumbs">
    
    <li class="breadcrumb-item breadcrumb-home">
      <a href="index.html" class="nav-link" aria-label="Home">
        <i class="fa-solid fa-home"></i>
      </a>
    </li>
    <li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">API Reference</span></li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section id="module-nvtx">
<span id="api-reference"></span><h1>API Reference<a class="headerlink" href="#module-nvtx" title="Link to this heading">#</a></h1>
<dl class="py class">
<dt class="sig sig-object py" id="nvtx.annotate">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">annotate</span></span><span class="sig-paren">(</span>

<dl>
<dd><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">domain</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">category</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">payload</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
</dl>

<span class="sig-paren">)</span><a class="headerlink" href="#nvtx.annotate" title="Link to this definition">#</a></dt>
<dd><p>Annotate code ranges using a context manager or a decorator.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>message</strong> – A message associated with the annotated code range.
When used as a decorator, defaults to the decorated function name.
When used as a context manager, defaults to the empty string.
Messages are cached and are registered as Registered Strings
in NVTX.
Caching a very large number of messages may lead to increased
memory usage.</p></li>
<li><p><strong>color</strong> – A color associated with the annotated code range.
Supports <cite>matplotlib</cite> colors if it is available.</p></li>
<li><p><strong>domain</strong> – A string specifying the domain under which the code range is
scoped. The default domain is named “NVTX”.</p></li>
<li><p><strong>category</strong> – A string or an integer specifying the category within the domain
under which the code range is scoped. If unspecified, the code
range is not associated with a category.</p></li>
<li><p><strong>payload</strong> – A numeric value to be associated with this event.</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">time</span>
</pre></div>
</div>
<p>Using a decorator:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@nvtx</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">color</span><span class="o">=</span><span class="s2">&quot;red&quot;</span><span class="p">,</span> <span class="n">domain</span><span class="o">=</span><span class="s2">&quot;my_domain&quot;</span><span class="p">):</span>    <span class="c1"># `message` defaults to &quot;func&quot;</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">func</span><span class="p">():</span>
<span class="gp">... </span>    <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>
</pre></div>
</div>
<p>Using a context manager:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">nvtx</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="s2">&quot;my_code_range&quot;</span><span class="p">,</span> <span class="n">color</span><span class="o">=</span><span class="s2">&quot;blue&quot;</span><span class="p">):</span>
<span class="gp">... </span>   <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="nvtx.push_range">
<span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">push_range</span></span><span class="sig-paren">(</span>

<dl>
<dd><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'blue'</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">domain</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">category</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">payload</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
</dl>

<span class="sig-paren">)</span><a class="headerlink" href="#nvtx.push_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the beginning of a code range.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>message</strong> – A message associated with the annotated code range.
Messages are cached and are registered as Registered Strings
in NVTX.
Caching a very large number of messages may lead to increased
memory usage.</p></li>
<li><p><strong>color</strong> – A color associated with the annotated code range.
Supports <cite>matplotlib</cite> colors if it is available.</p></li>
<li><p><strong>domain</strong> – Name of a domain under which the code range is scoped.
The default domain name is “NVTX”.</p></li>
<li><p><strong>category</strong> – A string or an integer specifying the category within the domain
under which the code range is scoped. If unspecified, the code range
is not associated with a category.</p></li>
<li><p><strong>payload</strong> – A numeric value to be associated with this event</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>When applicable, prefer to use <a class="reference internal" href="#nvtx.annotate" title="nvtx.annotate"><code class="xref py py-class docutils literal notranslate"><span class="pre">annotate</span></code></a>.
Otherwise, for best performance, use <a class="reference internal" href="#nvtx.Domain.push_range" title="nvtx.Domain.push_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.push_range()</span></code></a> and <a class="reference internal" href="#nvtx.Domain.pop_range" title="nvtx.Domain.pop_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.pop_range()</span></code></a>.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">time</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">nvtx</span><span class="o">.</span><span class="n">push_range</span><span class="p">(</span><span class="s2">&quot;my_code_range&quot;</span><span class="p">,</span> <span class="n">domain</span><span class="o">=</span><span class="s2">&quot;my_domain&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">nvtx</span><span class="o">.</span><span class="n">pop_range</span><span class="p">(</span><span class="n">domain</span><span class="o">=</span><span class="s2">&quot;my_domain&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="nvtx.pop_range">
<span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">pop_range</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">domain</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.pop_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the end of a code range that was started with <a class="reference internal" href="#nvtx.push_range" title="nvtx.push_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">push_range()</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>domain</strong> – The domain under which the code range is scoped. The default
domain is “NVTX”.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="nvtx.start_range">
<span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">start_range</span></span><span class="sig-paren">(</span>

<dl>
<dd><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">domain</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">category</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">payload</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
</dl>

<span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">int</span><span class="p"><span class="pre">]</span></span></span></span><a class="headerlink" href="#nvtx.start_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the beginning of a process range.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>message</strong> – A message associated with the range.
Messages are cached and are registered as Registered Strings
in NVTX.
Caching a very large number of messages may lead to increased
memory usage.</p></li>
<li><p><strong>color</strong> – A color associated with the range.
Supports <cite>matplotlib</cite> colors if it is available.</p></li>
<li><p><strong>domain</strong> – Name of a domain under which the range is scoped.
The default domain name is “NVTX”.</p></li>
<li><p><strong>category</strong> – A string or an integer specifying the category within the domain
under which the range is scoped. If unspecified, the range
is not associated with a category.</p></li>
<li><p><strong>payload</strong> – A numeric value to be associated with this event</p></li>
</ul>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>A tuple of the form <code class="docutils literal notranslate"><span class="pre">(range_id,</span> <span class="pre">domain_handle)</span></code> that must be passed to <a class="reference internal" href="#nvtx.end_range" title="nvtx.end_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">end_range()</span></code></a>.</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>For best performance, use <a class="reference internal" href="#nvtx.Domain.start_range" title="nvtx.Domain.start_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.start_range()</span></code></a> and <a class="reference internal" href="#nvtx.Domain.end_range" title="nvtx.Domain.end_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.end_range()</span></code></a>.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">time</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">range_id</span> <span class="o">=</span> <span class="n">nvtx</span><span class="o">.</span><span class="n">start_range</span><span class="p">(</span><span class="s2">&quot;my_code_range&quot;</span><span class="p">,</span> <span class="n">domain</span><span class="o">=</span><span class="s2">&quot;my_domain&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">nvtx</span><span class="o">.</span><span class="n">end_range</span><span class="p">(</span><span class="n">range_id</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="nvtx.end_range">
<span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">end_range</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">range_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">int</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.end_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the end of a code range that was started with <a class="reference internal" href="#nvtx.start_range" title="nvtx.start_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">start_range()</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>range_id</strong> – The tuple object returned by <a class="reference internal" href="#nvtx.start_range" title="nvtx.start_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">start_range()</span></code></a>.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="nvtx.mark">
<span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">mark</span></span><span class="sig-paren">(</span>

<dl>
<dd><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'blue'</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">domain</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">category</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">payload</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
</dl>

<span class="sig-paren">)</span><a class="headerlink" href="#nvtx.mark" title="Link to this definition">#</a></dt>
<dd><p>Mark an instantaneous event.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>message</strong> – A message associated with the event.
Messages are cached and are registered as Registered Strings
in NVTX.
Caching a very large number of messages may lead to increased
memory usage.</p></li>
<li><p><strong>color</strong> – Color associated with the event.
Supports <cite>matplotlib</cite> colors if it is available.</p></li>
<li><p><strong>domain</strong> – A string specifying the domain under which the event is scoped.
The default domain is named “NVTX”.</p></li>
<li><p><strong>category</strong> – A string or an integer specifying the category within the domain
under which the event is scoped. If unspecified, the event is
not associated with a category.</p></li>
<li><p><strong>payload</strong> – A numeric value to be associated with this event</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>For best performance, use <a class="reference internal" href="#nvtx.Domain.mark" title="nvtx.Domain.mark"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.mark()</span></code></a>.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">nvtx</span><span class="o">.</span><span class="n">mark</span><span class="p">(</span><span class="s2">&quot;my_marker&quot;</span><span class="p">,</span> <span class="n">domain</span><span class="o">=</span><span class="s2">&quot;my_domain&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="nvtx.get_domain">
<span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">get_domain</span></span><span class="sig-paren">(</span>

<dl>
<dd><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
</dl>

<span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#nvtx.Domain" title="nvtx._lib.lib.Domain"><span class="pre">Domain</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="#nvtx._lib.lib.DummyDomain" title="nvtx._lib.lib.DummyDomain"><span class="pre">DummyDomain</span></a></span></span><a class="headerlink" href="#nvtx.get_domain" title="Link to this definition">#</a></dt>
<dd><p>Get or create a <a class="reference internal" href="#nvtx.Domain" title="nvtx.Domain"><code class="xref py py-class docutils literal notranslate"><span class="pre">Domain</span></code></a> object for a domain name.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="nvtx.Domain">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">Domain</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.Domain" title="Link to this definition">#</a></dt>
<dd><p>A class that provides an interface to NVTX API per domain,
and produces less overhead than using the global functions from <code class="docutils literal notranslate"><span class="pre">nvtx</span></code> module.</p>
<p class="rubric">Notes</p>
<ul class="simple">
<li><p>Use <a class="reference internal" href="#nvtx.get_domain" title="nvtx.get_domain"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.get_domain()</span></code></a> to create an instance.</p></li>
<li><p>If the domain is disabled (e.g., when no tool is attached),
the instance returned is a <a class="reference internal" href="#nvtx._lib.lib.DummyDomain" title="nvtx._lib.lib.DummyDomain"><code class="xref py py-class docutils literal notranslate"><span class="pre">nvtx._lib.lib.DummyDomain</span></code></a>.</p></li>
</ul>
<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.mark">
<span class="sig-name descname"><span class="pre">mark</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">EventAttributes</span> <span class="pre">attributes</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.Domain.mark" title="Link to this definition">#</a></dt>
<dd><p>Mark an instantaneous event.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>attributes</strong> (<a class="reference internal" href="#nvtx._lib.lib.EventAttributes" title="nvtx._lib.lib.EventAttributes"><em>EventAttributes</em></a>) – The event attributes to be associated with the event.</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">domain</span> <span class="o">=</span> <span class="n">nvtx</span><span class="o">.</span><span class="n">Domain</span><span class="p">(</span><span class="s1">&#39;my_domain&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">attributes</span> <span class="o">=</span> <span class="n">domain</span><span class="o">.</span><span class="n">get_event_attributes</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s1">&#39;my_marker&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">domain</span><span class="o">.</span><span class="n">mark</span><span class="p">(</span><span class="n">attributes</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.push_range">
<span class="sig-name descname"><span class="pre">push_range</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">EventAttributes</span> <span class="pre">attributes</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.Domain.push_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the beginning of a code range.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>attributes</strong> (<a class="reference internal" href="#nvtx._lib.lib.EventAttributes" title="nvtx._lib.lib.EventAttributes"><em>EventAttributes</em></a>) – The event attributes to be associated with the range.</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>When applicable, prefer to use <a class="reference internal" href="#nvtx.annotate" title="nvtx.annotate"><code class="xref py py-class docutils literal notranslate"><span class="pre">annotate</span></code></a>.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">time</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">domain</span> <span class="o">=</span> <span class="n">nvtx</span><span class="o">.</span><span class="n">Domain</span><span class="p">(</span><span class="s1">&#39;my_domain&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">attributes</span> <span class="o">=</span> <span class="n">domain</span><span class="o">.</span><span class="n">get_event_attributes</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s1">&#39;my_code_range&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">domain</span><span class="o">.</span><span class="n">push_range</span><span class="p">(</span><span class="n">attributes</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">domain</span><span class="o">.</span><span class="n">pop_range</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.pop_range">
<span class="sig-name descname"><span class="pre">pop_range</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.Domain.pop_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the end of a code range that was started with <a class="reference internal" href="#nvtx.Domain.push_range" title="nvtx.Domain.push_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.push_range()</span></code></a>.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.start_range">
<span class="sig-name descname"><span class="pre">start_range</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">EventAttributes</span> <span class="pre">attributes</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">int</span></span></span><a class="headerlink" href="#nvtx.Domain.start_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the beginning of a process range.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>attributes</strong> (<a class="reference internal" href="#nvtx._lib.lib.EventAttributes" title="nvtx._lib.lib.EventAttributes"><em>EventAttributes</em></a>) – The event attributes to be associated with the range.</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>A numeric value that must be passed to <a class="reference internal" href="#nvtx.Domain.end_range" title="nvtx.Domain.end_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.end_range()</span></code></a>.</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">time</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">domain</span> <span class="o">=</span> <span class="n">nvtx</span><span class="o">.</span><span class="n">Domain</span><span class="p">(</span><span class="s1">&#39;my_domain&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">attributes</span> <span class="o">=</span> <span class="n">domain</span><span class="o">.</span><span class="n">get_event_attributes</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s1">&#39;my_code_range&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">range_id</span> <span class="o">=</span> <span class="n">domain</span><span class="o">.</span><span class="n">start_range</span><span class="p">(</span><span class="n">attributes</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">domain</span><span class="o">.</span><span class="n">end_range</span><span class="p">(</span><span class="n">range_id</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.end_range">
<span class="sig-name descname"><span class="pre">end_range</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nvtxRangeId_t</span> <span class="pre">range_id</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.Domain.end_range" title="Link to this definition">#</a></dt>
<dd><p>Mark the end of a process range that was started with <a class="reference internal" href="#nvtx.Domain.start_range" title="nvtx.Domain.start_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.start_range()</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>range_id</strong> (<em>int</em>) – The value returned by <a class="reference internal" href="#nvtx.Domain.start_range" title="nvtx.Domain.start_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">Domain.start_range()</span></code></a>.</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.get_event_attributes">
<span class="sig-name descname"><span class="pre">get_event_attributes</span></span><span class="sig-paren">(</span>

<dl>
<dd><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">category</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
<dd><em class="sig-param"><span class="n"><span class="pre">payload</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>,</dd>
</dl>

<span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#nvtx._lib.lib.EventAttributes" title="nvtx._lib.lib.EventAttributes"><span class="pre">EventAttributes</span></a></span></span><a class="headerlink" href="#nvtx.Domain.get_event_attributes" title="Link to this definition">#</a></dt>
<dd><p>Get or create an <a class="reference internal" href="#nvtx._lib.lib.EventAttributes" title="nvtx._lib.lib.EventAttributes"><code class="xref py py-class docutils literal notranslate"><span class="pre">nvtx._lib.lib.EventAttributes</span></code></a> object.
The results of this function are cached, i.e.,
the same object is returned for the same parameters.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>message</strong> (<em>str</em>) – A message associated with the event.</p></li>
<li><p><strong>color</strong> (<em>str</em><em>, </em><em>int</em><em>, </em><em>optional</em>) – A color associated with the event.
Supports <cite>matplotlib</cite> colors if it is available.</p></li>
<li><p><strong>category</strong> (<em>str</em><em>, </em><em>int</em><em>, </em><em>optional</em>) – A string or an integer specifying the category within the domain under which the event
is scoped. If unspecified, the event is not associated with a category.</p></li>
<li><p><strong>payload</strong> (<em>int</em><em>, </em><em>float</em><em>, </em><em>optional</em>) – A numeric value to be associated with this event.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.get_registered_string">
<span class="sig-name descname"><span class="pre">get_registered_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">string</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#nvtx._lib.lib.RegisteredString" title="nvtx._lib.lib.RegisteredString"><span class="pre">RegisteredString</span></a></span></span><a class="headerlink" href="#nvtx.Domain.get_registered_string" title="Link to this definition">#</a></dt>
<dd><p>Register a given string under this domain (on first use), and return the handle.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>string</strong> (<em>str</em>) – The string to be registered.</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="nvtx.Domain.get_category_id">
<span class="sig-name descname"><span class="pre">get_category_id</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">self</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">int</span></span></span><a class="headerlink" href="#nvtx.Domain.get_category_id" title="Link to this definition">#</a></dt>
<dd><p>Returns the category ID corresponding to the category <cite>name</cite>.
On first use with a specific <cite>name</cite>, a new ID is assigned with the given name.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>name</strong> (<em>str</em>) – The name of the category.</p>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="nvtx._lib.lib.EventAttributes">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">nvtx._lib.lib.</span></span><span class="sig-name descname"><span class="pre">EventAttributes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">category</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">payload</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx._lib.lib.EventAttributes" title="Link to this definition">#</a></dt>
<dd><p>A wrapper class for <code class="docutils literal notranslate"><span class="pre">nvtxEventAttributes_t</span></code> C struct.
Use <a class="reference internal" href="#nvtx.Domain.get_event_attributes" title="nvtx.Domain.get_event_attributes"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.Domain.get_event_attributes()</span></code></a> to create an instance.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="nvtx._lib.lib.EventAttributes.message">
<span class="sig-name descname"><span class="pre">message</span></span><a class="headerlink" href="#nvtx._lib.lib.EventAttributes.message" title="Link to this definition">#</a></dt>
<dd><p>A message associated with the event.
Retrieved by <a class="reference internal" href="#nvtx.Domain.get_registered_string" title="nvtx.Domain.get_registered_string"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.Domain.get_registered_string()</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="#nvtx._lib.lib.RegisteredString" title="nvtx._lib.lib.RegisteredString">RegisteredString</a></p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="nvtx._lib.lib.EventAttributes.color">
<span class="sig-name descname"><span class="pre">color</span></span><a class="headerlink" href="#nvtx._lib.lib.EventAttributes.color" title="Link to this definition">#</a></dt>
<dd><p>A color associated with the event.
Supports <cite>matplotlib</cite> colors if it is available.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str or int</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="nvtx._lib.lib.EventAttributes.category">
<span class="sig-name descname"><span class="pre">category</span></span><a class="headerlink" href="#nvtx._lib.lib.EventAttributes.category" title="Link to this definition">#</a></dt>
<dd><p>An integer specifying the category within the domain
under which the event is scoped.
If not set, the event is not associated with a category.
Retrieved by <a class="reference internal" href="#nvtx.Domain.get_category_id" title="nvtx.Domain.get_category_id"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.Domain.get_category_id()</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>int</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="nvtx._lib.lib.EventAttributes.payload">
<span class="sig-name descname"><span class="pre">payload</span></span><a class="headerlink" href="#nvtx._lib.lib.EventAttributes.payload" title="Link to this definition">#</a></dt>
<dd><p>A numeric value to be associated with this event.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>int</p>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="nvtx._lib.lib.RegisteredString">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">nvtx._lib.lib.</span></span><span class="sig-name descname"><span class="pre">RegisteredString</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">domain</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">string</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx._lib.lib.RegisteredString" title="Link to this definition">#</a></dt>
<dd><p>A wrapper class for <code class="docutils literal notranslate"><span class="pre">nvtxStringHandle_t</span></code> C struct.
Use <a class="reference internal" href="#nvtx.Domain.get_registered_string" title="nvtx.Domain.get_registered_string"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.Domain.get_registered_string()</span></code></a> to create an instance.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="nvtx._lib.lib.DummyDomain">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">nvtx._lib.lib.</span></span><span class="sig-name descname"><span class="pre">DummyDomain</span></span><a class="headerlink" href="#nvtx._lib.lib.DummyDomain" title="Link to this definition">#</a></dt>
<dd><p>A replacement for <a class="reference internal" href="#nvtx.Domain" title="nvtx.Domain"><code class="xref py py-class docutils literal notranslate"><span class="pre">nvtx.Domain</span></code></a> when the domain is disabled.
(e.g., when no tool is attached).</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="nvtx.Profile">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">nvtx.</span></span><span class="sig-name descname"><span class="pre">Profile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">linenos</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">annotate_cfuncs</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#nvtx.Profile" title="Link to this definition">#</a></dt>
<dd><p>Class for programmatically controlling NVTX automatic annotations.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>linenos</strong> – Include file and line number information in annotations.</p></li>
<li><p><strong>annotate_cfuncs</strong> – Also annotate C-extensions and builtin functions.</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">nvtx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">time</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pr</span> <span class="o">=</span> <span class="n">nvtx</span><span class="o">.</span><span class="n">Profile</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pr</span><span class="o">.</span><span class="n">enable</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="c1"># this call to `sleep` is captured by nvtx.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pr</span><span class="o">.</span><span class="n">disable</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="c1"># this one is not.</span>
</pre></div>
</div>
</dd></dl>

</section>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer d-print-none">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="automatic_annotations.html"
       title="previous page">
      <i class="fa-solid fa-angle-left"></i>
      <div class="prev-next-info">
        <p class="prev-next-subtitle">previous</p>
        <p class="prev-next-title">Automatic function annotation</p>
      </div>
    </a>
</div>
                </footer>
              
            </div>
            
            


              
                <dialog id="pst-secondary-sidebar-modal"></dialog>
                <div id="pst-secondary-sidebar" class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item">
<div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> On this page
  </div>
  <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.annotate"><code class="docutils literal notranslate"><span class="pre">annotate</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.push_range"><code class="docutils literal notranslate"><span class="pre">push_range()</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.pop_range"><code class="docutils literal notranslate"><span class="pre">pop_range()</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.start_range"><code class="docutils literal notranslate"><span class="pre">start_range()</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.end_range"><code class="docutils literal notranslate"><span class="pre">end_range()</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.mark"><code class="docutils literal notranslate"><span class="pre">mark()</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.get_domain"><code class="docutils literal notranslate"><span class="pre">get_domain()</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain"><code class="docutils literal notranslate"><span class="pre">Domain</span></code></a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.mark"><code class="docutils literal notranslate"><span class="pre">mark()</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.push_range"><code class="docutils literal notranslate"><span class="pre">push_range()</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.pop_range"><code class="docutils literal notranslate"><span class="pre">pop_range()</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.start_range"><code class="docutils literal notranslate"><span class="pre">start_range()</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.end_range"><code class="docutils literal notranslate"><span class="pre">end_range()</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.get_event_attributes"><code class="docutils literal notranslate"><span class="pre">get_event_attributes()</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.get_registered_string"><code class="docutils literal notranslate"><span class="pre">get_registered_string()</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Domain.get_category_id"><code class="docutils literal notranslate"><span class="pre">get_category_id()</span></code></a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx._lib.lib.EventAttributes"><code class="docutils literal notranslate"><span class="pre">EventAttributes</span></code></a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx._lib.lib.EventAttributes.message"><code class="docutils literal notranslate"><span class="pre">message</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx._lib.lib.EventAttributes.color"><code class="docutils literal notranslate"><span class="pre">color</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx._lib.lib.EventAttributes.category"><code class="docutils literal notranslate"><span class="pre">category</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx._lib.lib.EventAttributes.payload"><code class="docutils literal notranslate"><span class="pre">payload</span></code></a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx._lib.lib.RegisteredString"><code class="docutils literal notranslate"><span class="pre">RegisteredString</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx._lib.lib.DummyDomain"><code class="docutils literal notranslate"><span class="pre">DummyDomain</span></code></a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nvtx.Profile"><code class="docutils literal notranslate"><span class="pre">Profile</span></code></a></li>
</ul>
  </nav></div>

</div></div>
              
            

          </div>
          <footer class="bd-footer-content">
            
          </footer>
        
      </main>
    </div>
  </div>
  
  <!-- Scripts loaded after <body> so the DOM is not blocked -->
  <script defer src="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf"></script>
<script defer src="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf"></script>

  <footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
  
    <div class="footer-items__start">
      
        <div class="footer-item">
<a class="footer-brand logo" href="https://www.nvidia.com">
  <img src="_static/nvidia-logo-horiz-rgb-1c-blk-for-screen.svg" class="logo__image only-light" alt="NVIDIA"/>
  <img src="_static/nvidia-logo-horiz-rgb-1c-wht-for-screen.svg" class="logo__image only-dark" alt="NVIDIA"/>
</a></div>
      
        <div class="footer-item">

<div class="footer-links">
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/privacy-policy/">Privacy Policy</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/privacy-center/">Manage My Privacy</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/preferences/start/">Do Not Sell or Share My Data</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/terms-of-service/">Terms of Service</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/accessibility/">Accessibility</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/company-policies/">Corporate Policies</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/product-security/">Product Security</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/contact/">Contact</a>
  
  
  
</div>
</div>
      
        <div class="footer-item">




  <p class="copyright">
    
      Copyright © 2020-2025, NVIDIA Corporation.
      <br/>
    
  </p>
</div>
      
    </div>
  
  
  
</div>

  </footer>
  </body>
</html>